前言

歡迎來到第三天！賽程雖然才剛開始，但說實在話我已經累了:P 每次參賽前我都在心裡發誓一定要有一些存稿再來參加，結果每次參賽都是裸賽當天拚生死，怪不得當初研究所會搞到延畢！不過換個角度想，連我這樣的渣渣都能在工程師職場打滾，你們肯定能做得比我更好！一起繼續這次的旅程吧！
昨天我們成功地讓AI開口說話了，按下按鈕不再是寂寞的空響，我們確實善用了Gemini的免費額度呼叫了他的Api提供我們真正的回覆，
但如果你回去看昨天的程式碼與畫面，除了凌亂粗糙跟小學生作品之外我想不太出更貼切的形容詞，在專案一開始作為一個Prototyping勉強可以接受，但既然已經知道能做到與AI溝通，接著我們就要仔細思考我們到底打算用這樣的功能做出怎麼樣的產品，高階結構是怎麼樣的？畫面又大概要有哪些元素？實際上會使用到的工具又有哪些？這些初期設計能幫助我們整趟旅程更明確，也更容易在未來的開發中發現一些邏輯的衝突與瑕疵。我不保證目前的規劃在未來不會有任何變化，有可能技術上碰到一些障礙或是發現有更合適的架構都會做一點調整，也許賽程結束後再回頭來看目前的架構所剩無幾也是可能的，但這就是開發的一部分，若真的發生就當經驗吸收然後說服自己下次會更好吧！

今天，我們基本上不會碰到程式碼的部分，我們會針對整體結構、基本功能與ＵＩ和使用者流程做一版初步的設計，然後在未來的幾周內把它們全部套上去，最終就是個完整的成品囉！

今日目標

• 定義我們的使用者故事
• 完成初步架構設計
• 完成使用者流程規劃
• 完成設計線框稿

當然，這些東西你有大量的工具可以協助你完成，你不見得需要手把手一步步自己做全部的東西，我也是大概丟個想法給AI再統整出一套我覺得當下我能接受的版本！

應用程式規格：定義我們的使用者故事

在畫設計圖之前，讓我們先明確定義這個產品需要具備哪些核心功能。我們可以透過「使用者故事 (User Stories)」來描述，這能幫助我們聚焦在最重要的價值上。

身為一個前端學習者，我希望...

• 看到我的學習總覽：
  • 我想要在一個「主控台」頁面，看到我過去的練習次數、平均分數、以及在各個技術主題上的掌握度，這樣我才能了解自己的強項與弱點。
• 選擇我想練習的模式與主題：
  • 我想要可以自由選擇進行「概念問答」或是「程式實作」的練習。
  • 在選擇模式後，我想要看到所有可選的「主題」（如 JavaScript, React），並選擇一個我今天想專注加強的項目。
• 進行一場擬真的面試：
  • 在「概念問答」中，我想要一個純粹的對話介面，讓我能專心回答 AI 的提問。
  • 在「程式實作」中，我想要一個包含對話視窗和專業程式碼編輯器的工作區。
  • 我希望 AI 能像真人面試官一樣，在我回答後給我專業、有建設性的回饋。
• 回顧我的成長軌跡：
  • 我想要有一個「練習紀錄」頁面，條列出我過去每一次的練習歷史，包含日期、主題和成績，方便我回顧與複習。

暫時大概先定義這些使用者故事，未來功能新增時我們可以再擴展這個介面。

應用程式架構設計:列出整體結構

我們的專案稱不上有多大的規模，但也不至於簡陋到可以全部擠在一個前端頁面這種小地方的程度，除了牽扯到前後端的溝通之外，也要考慮外部服務像是我們剛串的Gemini model以及未來要串的向量資料庫或是向量API，為了避免開發混亂，我們盡可能地去做到一個基本設計原則：「關注點分離 (Separation of Concerns)」，讓彼此各司其職，盡可能不要出現姊代母職這種令人難過的情況出現。

我們可以把整個應用程式想像成一家高科技餐廳，裡面會有眾多不同的職位彼此配合工作：

• 前端 (Frontend)：餐廳的「外場服務生」，負責所有與使用者直接互動的工作。
• 我們的後端 (Backend / API Routes)：餐廳的「內場經理」，負責保管金鑰、協調所有後勤工作。
• 服務層 (Services)：各懷絕技的「廚師團隊」。
  • Google Gemini: 「創意總主廚」，負責 Code Review 與主觀分析。
  • isolated-vm/web worker/Judge0: 「品管主廚」，在我們後端內建的一個安全沙盒，負責提供程式碼能否運行的客觀事實。
  • Supabase (pgvector) & Gemini Embedding API: 共同組成了我們的「倉儲部門」，負責管理知識庫並快速找出相關資料。

轉成流程關係圖你可能可以更清楚整個應用程式的全貌，如下圖1所示:

圖1 :專案結構圖

坦白說我這個mermaid圖畫得沒有很好，也許你看了之後反而覺得更困惑了，可以搭配下方的文字說明，大致上的流程會是以下的步驟：

1. 提交：使用者在 React 前端介面提交答案（概念題）或程式碼（實作題）到我們的後端 API Route。
2. 執行：如果收到的是程式碼，後端會先在isolated-vm/web worker/Judge0的安全沙盒中執行它。若是概念題，則跳過此步驟。
3. 取得結果：後端取得程式碼的客觀執行結果（成功、失敗、錯誤訊息等）。
4. 轉換向量：後端將使用者的回答或問題，發送給 Gemini Embedding API，將其轉換成語意向量。
5. 取得向量：後端接收到代表使用者輸入語意的向量。
6. 語意搜尋：後端拿著這個向量，向 Supabase 向量資料庫發出查詢，請求返回語意上最相似的參考資料。
7. 取得 RAG 資料：後端從 Supabase 取得相關的上下文資料（例如：最佳實踐、標準答案等）。
8. 增強請求：後端將所有資訊（使用者的原始回答、程式碼執行結果、從 Supabase 拿到的 RAG 資料）打包成一個內容豐富的 Prompt，發送給 Gemini API。
9. AI 分析：Gemini 根據我們提供的完整上下文，進行深入的 Code Review 或概念評析，並回傳結果。
10. 呈現回饋：後端將 Gemini 的最終回饋傳回給前端，由 React 介面將其呈現在使用者眼前。

流程中有提到許多現在還沒有探討的概念，例如向量、Embedding之類的名詞，這些都預計在第二周之後的內容說明，到時候我們會花數天的大量篇幅去說明基本的觀念與實作，暫時你可以先把整個架構流程看過有個印象就好。

應用程式UI:設計頁面線框稿

下一步就是比較有實感的步驟了，畢竟有實際的畫面後要想像什麼的都變得很容易，但我必須說這也是我相對提不起勁的地方，雖然我作為前端工程師，但我自己對於美感什麼的自覺相當不足，工作上又多有專業的設計師去處理實際的布局跟畫面，我只要有足夠的能力去呈現他們的設計並妥善管理程式實作邏輯就好。不過有時候箭在弦上不得不發，還是有不少時刻需要考驗我這方面的能力，通常這種時候我會先有個大概的想像，接著將我的想法配合我大致上的使用者故事和情境描述丟給AI讓他出個幾版設計，我再選幾個符合我腦海畫面的作微調，雖然比不上專業設計師的成品，但做為示範作品通常效果不會太差，根據我們設計的使用者故事，大致上我們專案會需要以下幾個核心畫面。

Dashboard主控台

圖2 :主控台線框稿

測驗主題選擇頁面

圖3 :主題選擇線框稿

概念問題測驗頁面

圖4 :概念問題測驗線框稿

程式實作測驗頁面

圖5 :程式實作線框稿

練習紀錄頁面

圖6 :練習紀錄線框稿

練習詳情頁面

圖7 :練習記錄詳情線框稿

設定頁面跟整個Landing Page則暫時不是我們想關心的重點，我們在這次的旅程中會將主力重點先放在這幾個核心介面，行有餘力我們才會把剩餘的精力做其他頁面的新增或優化。幾個頁面的結構都蠻單純的，但足以讓使用者有個不錯的體驗了。

使用者核心操作流程:題目練習流程

最後一個部分則是實際的使用者流程，雖然我們在架構設計的部分已經粗略的描述了整個流程會怎麼進行，不過那部分並沒有包含配合UI畫面以及後端資料庫的一些行為，單純將重心放在整個架構上。我們不會把每一個使用者流程都再做詳細說明，我們只是要在這邊說明最核心的部分，也就是選題與答題的流程，如下圖8:

圖8 :使用者練習流程圖

1. 使用者選擇想練習的形式（概念問答｜程式實作）並選擇練習的主題，例如React。
2. 前端介面向後端服務發出該主題的請求。
3. 後端服務收到請求後向資料庫發出請求讀取內容(我們這邊先以簡單的json檔案當作資料庫。
4. 資料庫回傳指定主題的所有問題。
5. 後端服務隨機選擇該主題的一個題目。
6. 回傳給前端介面。
7. 前端在畫面上顯示該問題。

相當簡易的流程，配合之前的整個架構說明我想你已經大致了解整個應用程式的雛形與使用者的操作流程，看了這麼多說明之後是不是稍微窺見完成品的全貌了呢？當然，我必須再次強調這不過是計畫而已，未來開發過程中有變動是再正常也不過的事情，我們總是希望一開始在規劃時就考慮到每個細節，花大量時間做規劃直到我們認為每個環節都考慮到，但現實往往不是如此，臨時插進的需求、沒預料到的技術障礙或是一些現實條件的限制都可能會影響整個架構，我並不是在否定規劃的重要性，我只是先說明未來你的開發不完全按照原先的計畫是很正常的，不用給自己太大的壓力或真的意外發生時過於苛責自己！

今日回顧

結束啦！一點程式碼都沒寫的一天就這樣過去了，仿佛開了一整天的會結果一點寫code的時間都沒有對吧？雖然聽起來有點不對勁，但有在職場打滾過的你想必很清楚這也是工程師日常的一部分！你要相信這些時間都是有意義的！回顧一下我們今天完成的部分吧，這樣你會覺得好一些，你可是真的有產值的！

✅ 定義使用者故事
✅ 完成架構設計
✅ 提出數個頁面線框稿
✅ 定義使用者核心流程

明天預告

明天（Day ４）我們則是會把重心放到我們最後使用者流程中有提到的一部分，也就是題庫資料庫的管理！當然我們不會在一開始就完全導入真正的資料庫使用，我可不希望你在設置時就嫌麻煩跑走了，第一周主要還是屬於ＭＶＰ的階段，我們重點要放在驗證流程可行，做最小成本的實踐之後再在之後的時間遷移成更完整的結構！今天也辛苦啦，我們明天見！

今日程式碼: 今天沒有程式碼！

#17th鐵人賽 #next.js #gemini #llm #react